Mule : Axis SOAP Styles
This page last changed on Jul 20, 2006 by stephen fenech.

By Default Mule Axis support uses RPC/Encoded for soap messages. However, due to compatability issues on other platforms it has become increasingly popular to use Document/Litteral/Wrapped stye services. The follwoing document descries how to use Doc/Lit, Doc/Lit/Wrapped and Message style services using Axis in Mule. For a really good overview of the pros and cons of each style/use combination have a look at - http://www-128.ibm.com/developerworks/webservices/library/ws-whichwsdl/.

For each example we provide a client call and a server example. The Client example shows how to invoke an Axis web service hosted in Tomcat using the Mule client. The example behaves exactly the same way if the service is hosted in Mule unless explicitly noted otherwise. The Server example demonstrates how to expose a service in Mule with any additional steps that may be necessary.

These tests were run against Tomcat 5.5.12 and Axis 1.3.1. Each test uses the Calculator service as used in the Axis User Guide.

Document Literal Wrapped

This is the preferred approach to Document Literal style services. The 'Wrapped' bit just means that the parameters are wrapped in an element whose name is the name of the operation to invoke.

Client Example

This example is very similar to the Doc/Lit example except that we set the message style to 'wrapped/literal' and there is not need to add any server configuration as the method name is stored in the message.

String URL = "axis:http://localhost:8080/axis/Calculator.jws?method=add";
MuleClient client = new MuleClient();
Map props = new HashMap();
props.put("style", "wrapped");
props.put("use", "literal");
UMOMessage result = client.send(URL, new Object[]{new Integer(3), new Integer(3)}, props);
assertEquals(result.getPayload(), new Integer(6));

The soap request for this call looks like -

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <add xmlns="">
            <value0 xsi:type="xsd:int">3</value0>
            <value1 xsi:type="xsd:int">3</value1>
        </add>
    </soapenv:Body>
</soapenv:Envelope>

In the next example we can see how to change the namespace of the method as well as naming the parameters. This is obviously very useful when calling services from other platforms!

Doc/Lit/Wrapped with Named Paramters

If you're invoking external services you will quickly find that the Axis generated names for parameters and namespaces will break things. However, it is trivial to change these in Mule. The following example demonstrates -

Client Example

String URL = "axis:http://localhost:8080/axis/Calculator.jws";
MuleClient client = new MuleClient();

SoapMethod method = new SoapMethod(new QName("http://muleumo.org/Calc", "add"));
method.addNamedParameter(new QName("Number1"), NamedParameter.XSD_INT, "in");
method.addNamedParameter(new QName("Number2"), NamedParameter.XSD_INT, "in");
method.setReturnType(NamedParameter.XSD_INT);

Map props = new HashMap();
props.put("style", "wrapped");
props.put("use", "literal");
props.put("method", method);
UMOMessage result = client.send(URL, new Object[]{new Integer(3), new Integer(3)}, props);
assertEquals(result.getPayload(), new Integer(6));

Notice that we no long pass the method name in the query string of the URL, instead we create a SoapMethod object and add it to the parameters we pass to the client call.

The soap request now looks like -

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <add xmlns="http://muleumo.org/Calc">
            <Number1 xsi:type="xsd:int" xmlns="">3</Number1>
            <Number2 xsi:type="xsd:int" xmlns="">3</Number2>
        </add>
    </soapenv:Body>
</soapenv:Envelope>

Moving this information into configuration

Sometimes you might not want to have Namespaces and parameter names hard-coded in your code, instead you can moving to a Mule config file. You just need to create an endpoint configuration in the MuleXml configuration and reference it from your Mule Client. the Config file will look like -

<mule-configuration id="axis_client_endpoint" version="1.0">
    <global-endpoints>
        <endpoint name="calculatorAddEndpoint" address="axis:http://localhost:8080/axis/Calculator.jws?method=add">
            <properties>
                <property name="style" value="wrapped"/>
                <property name="use" value="literal"/>
                <map name="soapMethods">
                    <list name="qname{add:http://muleumo.org/Calc}">
                        <entry value="Number1;int;in"/>
                        <entry value="Number2;int;in"/>
                        <entry value="return;int"/>
                    </list>
                </map>
            </properties>
        </endpoint>
    </global-endpoints>
</mule-configuration>

This endpoint configuration can be used by the MuleClient or on a component outbound router.

The client code is now much more simplified -

MuleClient client = new MuleClient("org/mule/test/integration/providers/soap/axis/soap-client-endpoint-config.xml");

UMOMessage result = client.send("calculatorAddEndpoint", new Object[]{new Integer(3), new Integer(3)}, null);
assertEquals(result.getPayload(), new Integer(6));

Notice for the URL for the MuleClient call we pass in the name of the service endpoint not the physiscal location of the resource.

Document Literal


Mule hosted Web services using Axis cannot be invoked using Doc/Lit, Doc/Lit/Wrapped should be used instead. Users can still invoke remote web services using Doc/Lit as shown in the example below.

Client Example

For this example we must tell the Mule client to use 'dcouent/literal' for the message style, and we pass this information into the cal on the MuleClient. However, this will not work without some configuration on the Axis server. The biggest limitation of Doc/Lit is that operation/method name is not passed with the message

String URL = "axis:http://localhost:8080/axis/Calculator.jws?method=add";
MuleClient client = new MuleClient();
Map props = new HashMap();
props.put("style", "document");
props.put("use", "literal");
UMOMessage result = client.send(URL, new Object[]{new Integer(3), new Integer(3)}, props);
assertEquals(result.getPayload(), new Integer(6));

The soap request for this call looks like -

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <value0 xsi:type="xsd:int">3</value0>
        <value1 xsi:type="xsd:int">3</value1>
    </soapenv:Body>
</soapenv:Envelope>

Using Doc/Lit with Axis sometimes may appear to work even when you don't add Operation info to the Axis Server configuration. This happens when there is a single parameter for the service and the parameter name (see Axis Operations) is the same as the operation/method name you want to invoke.

RPC Encoded

Client Example

Because Axis uses RPC/Encoded by default there is no need to pass any additional config information.

String URL = "axis:http://localhost:8080/axis/Calculator.jws?method=add";
MuleClient client = new MuleClient();
UMOMessage result = client.send(URL, new Object[]{new Integer(4), new Integer(3)}, null);
assertEquals(result.getPayload(), new Integer(7));

The soap request for this call looks like -

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <add soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
            <value0 href="#id0"/>
            <value1 href="#id1"/>
        </add>
        <multiRef id="id0" soapenc:root="0" soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                  xsi:type="soapenc:int" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">4</multiRef>
        <multiRef id="id1" soapenc:root="0" soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
                  xsi:type="soapenc:int" xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/">3</multiRef>
    </soapenv:Body>
</soapenv:Envelope>

Using the WSDL Url

TODO

Client Example





				    
                    			    		
		    

	    

	    

			

				
			

		    

			    Document generated by Confluence on Nov 27, 2006 10:27